ctutil.h functionality reference

The ProtectToolkit-C Software Development Kit (SDK) offers a number of extended API libraries with functionality that is extended to that of the standard PKCS#11 function set.

The following additional features do not form part of the standard PKCS#11 functionality, but are provided by Thales as part of the SafeNet ProtectToolkit-C API within the ctutil.h library.

BuildDhKeyPair

Create a DH key pair given the required components.

Synopsis

CK_RV BuildDhKeyPair(
CK_SESSION_HANDLE hSession,
char * txt,
int tok,
int priv,
CK_OBJECT_HANDLE * phPub,
CK_OBJECT_HANDLE * phPri,
char * prime,
char * base,
char * pub,
char * pri);

On successful return

*phPub — handle to newly-created public key

*phPri — handle to newly-created private key

In addition to the Public key attributes set via the parameters, the following are set:

CKA_CLASS CKO_PUBLIC_KEY 
CKA_KEY_TYPE CKK_DH 
CKA_EXTRACTABLE TRUE

In addition to the Private key attributes set via the parameters, the following are set:

CKA_CLASS CKO_PRIVATE_KEY 
CKA_KEY_TYPE CKK_DH 
CKA_EXTRACTABLE TRUE

BuildDsaKeyPair

Create DSA key pair given required components.

Synopsis

CK_RV BuildDsaKeyPair(
CK_SESSION_HANDLE hSession,
char * txt,
int tok,
int priv,
CK_OBJECT_HANDLE * phPub,
CK_OBJECT_HANDLE * phPri,
char * prime,
char * subprime,
char * base,
char * pub,
char * pri);

On successful return

*phPub — handle to newly created public key

*phPri — handle to newly created private key

In addition to the Public key attributes set via the parameters, the following are set:

CKA_CLASS CKO_PUBLIC_KEY 
CKA_KEY_TYPE CKK_DSA 
CKA_EXTRACTABLE TRUE

In addition to the Private key attributes set via the parameters, the following are set:

CKA_CLASS CKO_PRIVATE_KEY 
CKA_KEY_TYPE CKK_DSA 
CKA_EXTRACTABLE TRUE

BuildRsaCrtKeyPair

Create an RSA key pair given the modulus and exponents, as well as the additional arguments used in Chinese Remainder Theorem processing. If the values for P, Q, E1, E2 and U are not specified, a normal RSA key pair is created.

Synopsis

CK_RV BuildRsaCrtKeyPair(
CK_SESSION_HANDLE hSession,
char * txt,
int tok,
int priv,
CK_OBJECT_HANDLE * phPub,
CK_OBJECT_HANDLE * phPri,
char * modulusStr,
char * pubExpStr,
char * priExpStr,
char * priPStr,
char * priQStr,
char * priE1Str,
char * priE2Str,
char * priUStr);

On successful return

*phPub — handle to newly created public key

*phPri — handle to newly created private key

In addition to the Public key attributes set via the parameters, the following are set:

CKA_CLASS 
CKO_PUBLIC_KEY 
CKA_KEY_TYPE 
CKK_RSA 
CKA_VERIFY TRUE 
CKA_SIGN FALSE 
CKA_DECRYPT FALSE 
CKA_ENCRYPT TRUE 
CKA_EXTRACTABLE TRUE 
CKA_WRAP FALSE

In addition to the Private key attributes set via the parameters, the following are set:

CKA_CLASS 
CKO_PRIVATE_KEY 
CKA_KEY_TYPE 
CKK_RSA 
CKA_VERIFY FALSE 
CKA_SIGN TRUE 
CKA_DECRYPT TRUE 
CKA_ENCRYPT FALSE 
CKA_EXTRACTABLE TRUE 
CKA_WRAP FALSE

BuildRsaKeyPair

Create an RSA key pair given the modulus and exponents.

Synopsis

CK_RV BuildRsaKeyPair(
CK_SESSION_HANDLE hSession,
char * txt,
int tok,
int priv,
CK_OBJECT_HANDLE * phPub,
CK_OBJECT_HANDLE * phPri,
char * modulusStr,
char * pubExponentStr,
char * priExponentStr);

On successful return

*phPub — handle to newly created public key

*phPri — handle to newly created private key

In addition to the Public key attributes set via the parameters, the following are set:

CKA_CLASS 
CKO_PUBLIC_KEY 
CKA_KEY_TYPE 
CKK_RSA 
CKA_VERIFY TRUE 
CKA_SIGN FALSE 
CKA_DECRYPT FALSE 
CKA_ENCRYPT TRUE 
CKA_EXTRACTABLE TRUE 
CKA_WRAP FALSE

In addition to the Private key attributes set via the parameters, the following are set:

CKA_CLASS 
CKO_PRIVATE_KEY 
CKA_KEY_TYPE 
CKK_RSA 
CKA_VERIFY FALSE 
CKA_SIGN TRUE 
CKA_DECRYPT TRUE 
CKA_ENCRYPT FALSE 
CKA_EXTRACTABLE TRUE 
CKA_WRAP FALSE

C_ErrorString

Convert a Cryptoki error code into a printable string. Note that this function is not a part of the PKCS#11 definition.

The sample programs use this extensively to map Cryptoki error numbers to meaningful text to display to the user.

Synopsis

CK_RV C_ErrorString(CK_RV ret, char * errstr, unsigned int len);

calcKvc

Calculate and return an AS2805 KVC for a key. The key must be capable of doing an encryption operation using the mechanism determined from the key type (see mechFromKt) for this to succeed.

Synopsis

CK_RV calcKvc(
CK_SESSION_HANDLE hSession,
CK_OBJECT_HANDLE hKey,
unsigned char * kvc,
int kvclen,
int * pkvclen);

On successful return

kvc — holds the encryption result

*pkvclen — number of bytes copied into kvc

If kvclen is smaller than the encryption result, then only kvclen bytes are copied into kvc.

calcKvcMech

Calculate and return an AS2805 KVC for a key. The key must be capable of doing an encryption operation using the supplied mechanism for this to succeed.

Synopsis

CK_RV calcKvcMech(
CK_SESSION_HANDLE hSession,
CK_OBJECT_HANDLE hKey,
CK_MECHANISM_TYPE mt,
unsigned char * kvc,
int kvclen,
int * pkvclen);

On successful return

kvc — holds the encryption result

*pkvclen — number of bytes copied into kvc

If kvclen is smaller than the encryption result, then only kvclen bytes are copied into kvc.

cDump

Dump buf contents in hex via printf.

Synopsis

int cDump(char * title,unsigned char * buf,unsigned int len);

CheckCryptokiVersion

Thales supports multiple versions of PKCS#11, but V 1.x and v 2.x are incompatible. An application compiled for V 1.x compliance is likely to crash if it links against a V 2.x compliant DLL, and vice versa.

This function is used to check that the version of CRYPTOKI is correct for the application and will report if an incompatible Cryptoki DLL is loaded. The application should report this fact and terminate.

All the sample applications make this call to check the Cryptoki version they are running.

Synopsis

CK_RV CheckCryptokiVersion(void);

CreateDesKey

Create a secret key object, and set the key type to CKK_DES, CKK_DES2 or CKK_DES3 (based on len).

Synopsis

CK_RV CreateDesKey(
CK_SESSION_HANDLE hSession,
char * txt,
int tok,
int priv,
CK_BYTE * keyValue,
int len,
CK_OBJECT_HANDLE * phKey);

On successful return

*phKey — handle to newly created key

In addition to the key attributes set via the parameters, the following are set:

CKA_CLASS CKO_SECRET_KEY 
CKA_KEY_TYE CKK_DES, CKK_DES2 OR CKK_DES3
CKA_ID “ID” 
CKA_DERIVE TRUE 
CKA_EXTRACTABLE TRUE 
CKA_UNWRAP TRUE 
CKA_WRAP FALSE

CreateSecretKey

Create a secret key object.

Synopsis

CK_RV CreateSecretKey(
CK_SESSION_HANDLE hSession,
char * txt,
int tok,
int priv,
CK_KEY_TYPE kt,
CK_BYTE * keyValue,
int len,
CK_OBJECT_HANDLE * phKey);

On successful return

*phKey — handle to newly created key

In addition to the key attributes set via the parameters, the following are set:

CKA_CLASS CKO_SECRET_KEY 
CKA_ID “ID” 
CKA_DERIVE TRUE 
CKA_EXTRACTABLE TRUE 
CKA_UNWRAP TRUE 
CKA_WRAP FALSE

CT_AttrToString

Get the value of the given attribute as a printable string

Synopsis

CK_RV CT_AttrToString(CK_ATTRIBUTE_PTR pAttr,char* pStringVal,CK_SIZE* pStringValLen);

On successful return

*pStringVal — pointer to the returned string value

*pStringValLen — length of the string

CT_CreateObject

Create a private token object of the specified class with the defined label.

Synopsis

CK_RV CT_CreateObject(
CK_SESSION_HANDLE hSession,
CK_OBJECT_CLASS cl,
char * name,
CK_OBJECT_HANDLE * phObj); Parameters

On successful return

*phObj — handle to the newly created object

CT_CreatePublicObject

Create a public token object of the specified class with the defined label.

Synopsis

CK_RV CT_CreatePublicObject(
CK_SESSION_HANDLE hSession,
CK_OBJECT_CLASS cl,
char * name,
CK_OBJECT_HANDLE * phObj);

On successful return

*phObj — handle to the newly created object

CT_Create_Set_Attributes_Ticket_Info

The function creates an unsigned CKM_SET_ATTRIBUTES ticket.

The function supports length prediction.

See CT_Create_Set_Attributes_Ticket.

Synopsis

CK_RV CT_Create_Set_Attributes_Ticket_Info( 
/* specify the target */
    CK_MECHANISM_TYPE objectDigestAlg, /* digest alg */
    unsigned char * objectDigest, /* digest of target object */
    unsigned int objectDigestLen,
    /* specify issuer */
    char * issuerRDN,       /* may be NULL or 
                            * DER of DistName or 
                            * Common Name string or
                            * RDN Seq string (CN=Fred+C=USA) */
    unsigned int issuerRDNLen,

/* ticket details */
    CK_MECHANISM_TYPE signatureAlg, /* signature alg */
    unsigned long sno,      /* Attrib Cert serial number */
    char * notBefore,       /* YYYYMMDD string */
    char * notAfter,        /* YYYYMMDD string */

/* attributes on key to modify */
    unsigned long * limit,  /* NULL if no CKA_USAGE_LIMIT */
    char * start,           /* NULL if no CKA_START_DATE */
    char * end,             /* NULL if no CKA_END_DATE */
    char * cert,            /* NULL if no CKA_ADMIN_CERT */
    unsigned int certLen,

/* output */
        void * pTicketInfo,    /* OUT new unsigned ticket returned here */
        unsigned int* puiTicketLen; /* IN/OUT pTicketInfo buffer length */
);

CT_Create_Set_Attributes_Ticket

The function combines the AttributeCertificateInfo DER encoding returned from the CT_Create_Set_Attributes_Ticket_Info function with a digital signature to form the DER encoded AttributeCertificate that can be passed to a CT_PresentTicket function using the CKM_SET_ATTRIBUTES mechanism.

Synopsis

CK_RV CT_Create_Set_Attributes_Ticket( 
void * pTicketInfo,    /* IN unsigned ticket */
unsigned int uiTicketInfoLen; /* IN pTicketInfo buffer length */

CK_MECHANISM_TYPE signatureAlg, /* signature alg */
unsigned char * pSignature, /* signature of pTicketData */
unsigned int uiSigLen; /* IN pSignature buffer length */

void * pTicketData,    /* OUT new unsigned ticket returned here */
unsigned int * puiTicketLen; /* IN/OUT pTicketData buffer length */
);

CT_DerEncodeNamedCurve

Helper function to provide the DER encoding of a supported named curve. This function is typically used to populate the CKA_EC_PARAMS attribute of the template used during EC key pair generation.

Synopsis

CK_RV CT_DerEncodeNamedCurve(
CK_BYTE_PTR buf,
CK_SIZE_PTR len,
const char *name);

Supported Curves

On successful return

buf — contains a string.

Example: “hh:mm:ss DD/MM/YYYY“ *len Number of bytes copied to buf

To determine the encoding length, pass in NULL for buf and check the resulting value of *len.

curve25519

Supported Operations

Parameters

Curve25519 uses the CKM_ECDH1_DERIVE mechanism. Users are required to use the CKM_ECDH1_DERIVE mechanism and fill in the CK_ECDH1_DERIVE_PARAMS structure to access Curve25519.

For more information about the key derivation mechanism see CKM_ECDH1_DERIVE

ed25519

Supported Operations

CT_GetObjectDigest

Compute the object digest as used by SET Attributes Ticket to identify the target object.

Synopsis

CK_RV CT_GetObjectDigest(
    CK_SESSION_HANDLE hSession,  /* IN */
    CK_OBJECT_HANDLE hObject,    /* IN */
    CK_MECHANISM_PTR pDigestMech,/* IN */

    CK_BYTE_PTR * ppDigest,  /* OUT returned buffer must be freed */
    CK_ULONG    * pulDigest  /* OUT length of returned buffer */
            );

CT_GetECCDomainParameters

This function returns the DER encoded Domain Parameters for a curve specified by name.

First the CT_DerEncodeNamedCurve function is used to see if the curve is known to the HSM. If not, then this function looks up the appropriate Domain Parameter object in the token indicated by hSession.

Synopsis

#include“ctlutil.h”

Windows Library: ctlutil.lib

Unix Library: Libctlutil.a

CK_RV CT_GetECCDomainParameters(
CK_SESSION_HANDLE hSession,
CK_ATTRIBUTE_PTR  attr,
const char *name)

CT_GetObjectDigestFromParts

Compute the object digest as used by SET Attributes Ticket to identify the target object by using parts.

See also CT_GetObjectDigest.

Synopsis

CK_RV CT_GetObjectDigestFromParts(
        CK_SESSION_HANDLE hSession,  /* IN */
        CK_MECHANISM_PTR pDigestMech,/* IN */
        char * tokenSerialNumber,    /* IN */
        char * tokenLabel,           /* IN */
        char * objLabel,             /* IN */
        CK_BYTE_PTR  objID,          /* IN */
        CK_ULONG     objIDlen,       /* IN */

        CK_BYTE_PTR * ppDigest,   /* OUT returned buffer 
(must be freed by caller) */
        CK_ULONG    * pulDigest   /* OUT length of returned buffer */
                );

CT_ErrorString

Get a printable string representation of a Cryptoki error code.

Synopsis

CK_RV C_ErrorString(
CK_RV ret,
char * errstr,
unsigned int len); Parameters

On successful return

errstr — contains the printable string, or as much as will fit.

CT_GetECKeySize

Helper function to return key size (in bits) for a given EC parameter

Synopsis

CK_RV CT_GetECKeySize(const CK_ATTRIBUTE_PTR ecParam,CK_SIZE_PTR size);

On successful return

size — pointer to the value of key size

CT_MakeObjectNonModifiable

Change an object CKA_MODIFIABLE attribute from TRUE to FALSE.

This involves copying the object - so the handle of the object will change.

The original object is deleted.

Synopsis

CK_RV CT_MakeObjectNonModifiable( 
        CK_SESSION_HANDLE hSession,   /* IN */
        CK_OBJECT_HANDLE  hObj,       /* IN */
        CK_OBJECT_HANDLE *phObj       /* OUT (may be NULL) */
                                );

CT_OpenObject

Get a handle to an object with the specified class and label. This function returns the first object satisfying the criteria.

Synopsis

CK_RV CT_OpenObject(
CK_SESSION_HANDLE hSession,
CK_OBJECT_CLASS cl,
char * name,
CK_OBJECT_HANDLE * phObj);

On successful return

*phObj — handle to the opened object

CT_ReadObject

Get the value of an object.

Synopsis

CK_RV CT_ReadObject(
CK_SESSION_HANDLE hSession,
CK_OBJECT_HANDLE hObj,
unsigned char * buf,
unsigned int len,
unsigned int * pbr); Parameters

On successful return

buf — contains the object value

*pbr — number of bytes copied into buf

If buf is too small to hold the attribute value (that is, len is < attribute value length), then CKR_ATTRIBUTE_TYPE_INVALID is returned.

To determine the attribute value length, pass in 0 for len, and check the resulting value of *pbr.

CT_RenameObject

Change the label of the object with the specified class and label.

Synopsis

CK_RV CT_RenameObject(
CK_SESSION_HANDLE hSession,
CK_OBJECT_CLASS cl,
char * oldName,
char * newName);

CT_SetCKDateStrFromTime

Convert time_t structure to the DATE format used by CT_SetLimitsAttributes and CT_Create_Set_Attributes_Ticket_Info.

Synopsis

void  CT_SetCKDateStrFromTime(
 char pd[9], /* OUT - pointer to a buffer at least 9 bytes*/
 time_t *t);  /* IN - time value to convert */

CT_Structure_To_Armor

Armoring is the term used in PGP and MIME to describe the formatting of binary data such that it can be unambiguously embedded in a printable document such as an email.

The Base 64 encoding method is used to make binary data printable and the encoding is clearly marked with BEGIN and END statements.

The function formats an arbitary structure - such as a ticket - into an Armored (printable format).

The result is returned as a buffer that the caller must free after use.

Synopsis

CK_RV CT_Structure_To_Armor(

    char *  pLabel,/* IN Armor label (string) */
    char * pComment,/* optional comment string */
    CK_VOID_PTR pData, /* IN data to armor */
    CK_ULONG ulDataLen /* IN length of data */

    CK_BYTE_PTR *pArmor, /* OUT Armored structure created 
(free after use) */
    CK_ULONG_PTR pulArmorLen /* IN/OUT pArmor buffer length */
);

Example

If Armoring the binary data 01h 23h 45h 67h 89h abh cdh efh with the label “SETATTRIBUTE TICKET” and the comment “This is a trial certificate\n”.

You get:

This is a trial certificate
-----BEGIN SETATTRIBUTE TICKET-----
ASNFZ4mrze8=
-----END SETATTRIBUTE TICKET-----

CT_Structure_From_Armor

Armoring is the term used in PGP and MIME to describe the formatting of binary data such that it can be unambiguously embedded in a printable document such as an email.

The function extracts a data structure from an Armored (printable format) buffer.

The result is returned as a buffer that the caller must free after use.

Synopsis

CK_RV CT_Structure_From_Armor (

    Char * pLabel,/* IN Armor label (string) */
    CK_BYTE_PTR pArmor,/* IN Armored structure */
    CK_ULONG ulArmorLen /* IN pArmor buffer length */

    CK_VOID_PTR *pData, /* OUT extracted structure */
    CK_ULONG_PTR pulDataLen /* OUT *pData buffer length */
);

CT_SetLimitsAttributes

Apply limit attributes to an object. The optional inputs can be set to NULL to indicate that that Attributes should not be set.

Synopsis

CK_RV CT_SetLimitsAttributes( 
    CK_SESSION_HANDLE hSession, /* IN */
    CK_OBJECT_HANDLE  hObj,     /* IN */
    CK_VOID_PTR pCertData,    /* IN - optional CKA_ADMIN_CERT value */
    CK_ULONG    ulCertDataLen, /* IN - length of pCertData */
    CK_ULONG    * usage_limit,  /* IN - optional CKA_USAGE_LIMIT */
    CK_ULONG    * usage_count,  /* IN - optional CKA_USAGE_COUNT */
    char *        start_date,   /* IN - optional CKA_START_DATE */
    char *        end_date      /* IN - optional CKA_END_DATE */
                );

CT_WriteObject

Set the value of an object.

Synopsis

CK_RV CT_WriteObject(
CK_SESSION_HANDLE hSession,
CK_OBJECT_HANDLE hObj,
const unsigned char * buf,
unsigned int len,
unsigned int * pbr);

On successful return

*pbr — set to equal len

DateConvertGmtToLocal

Converts a GMT date string of the format YYYYMMDDhhmmssxx into the Local Time format "DD/MM/YYYY hh:mm:ss (TimeZone)".

Synopsis

DateConvertGmtToLocal(char * fmt,const char * ts);

On successful return

*fmt — pointer to the buffer that holds the converted value

DateConvert

Convert “YYYYMMDDhhmmss00” to “hh:mm:ss DD/MM/YYYY“.

Synopsis

void DateConvert(
char * fmt,
const char * ts); Parameters

On successful return

fmt — contains a string like "hh:mm:ss DD/MM/YYYY"

DumpAttributes

Dumps attribute details via logtrace.

Synopsis

void DumpAttributes(CK_ATTRIBUTE * na,CK_COUNT attrCount);

DumpDHKeyPair

Dump DH key pair details via printf.

Synopsis

CK_RV DumpDHKeyPair(
int cStyle,
CK_SESSION_HANDLE hSession,
CK_OBJECT_HANDLE hPub,
CK_OBJECT_HANDLE hPri);

DumpDSAKeyPair

Dump DSA key pair details via printf.

Synopsis

CK_RV DumpDSAKeyPair(
int cStyle,
CK_SESSION_HANDLE hSession,
CK_OBJECT_HANDLE hPub,
CK_OBJECT_HANDLE hPri);

DumpRSAKeyPair

Dump RSA key pair details via printf.

Synopsis

CK_RV DumpRSAKeyPair(
int cStyle,
CK_SESSION_HANDLE hSession,
CK_OBJECT_HANDLE hPub,
CK_OBJECT_HANDLE hPri);

FindAttribute

Find the first attribute of the specified type in an attribute template.

Synopsis

CK_ATTRIBUTE * FindAttribute(
CK_ATTRIBUTE_TYPE attrType,
const CK_ATTRIBUTE * attr,
CK_COUNT attrCount);

On successful return

Return a pointer to the attribute of the specified type.

FindKeyFromName

Find the key with a given class and label within the specified token, and open a session to this token.

Synopsis

CK_RV FindKeyFromName(
const char * keyName,
CK_OBJECT_CLASS cl,
CK_SLOT_ID * phSlot,
CK_SESSION_HANDLE * phSession,
CK_OBJECT_HANDLE * phKey);

On successful return

*phSlot — slot holding the key

*phSession — open session handle

*phKey — handle to the key object

FindTokenFromName

Find a token with the specified label and return the corresponding slot id.

Synopsis

CK_RV FindTokenFromName(
char * label,
CK_SLOT_ID * pslotID); Parameters

On successful return

*pslotID — slot which contains the Token

GenerateDhKeyPair

Generate a DH key pair.

Synopsis

CK_RV GenerateDhKeyPair(
CK_SESSION_HANDLE hSession,
char * txt,
int ftok,
int priv,
int param,
CK_SIZE valueBits,
CK_OBJECT_HANDLE * phPublicKey,
CK_OBJECT_HANDLE * phPrivateKey);

On successful return

*phPublicKey — handle to newly created public key

*phPrivateKey — handle to newly created private key

In addition to the Public key attributes set via the parameters, the following are set:

CKA_CLASS CKO_PUBLIC_KEY 
CKA_KEY_TYPE CKK_DH 
CKA_VERIFY TRUE 
CKA_EXTRACTABLE TRUE

In addition to the Private key attributes set via the parameters, the following are set:

CKA_CLASS CKO_PRIVATE_KEY 
CKA_KEY_TYPE CKK_DH 
CKA_SUBJECT_STR “SUBJECT” 
CKA_ID 123 
CKA_SENSITIVE TRUE 
CKA_SIGN TRUE 
CKA_EXTRACTABLE TRUE

GenerateDsaKeyPair

Generate DSA key pair.

Synopsis

CK_RV GenerateDsaKeyPair(
CK_SESSION_HANDLE hSession,
char * txt,
int ftok,
int priv,
int param,
CK_SIZE valueBits,
CK_OBJECT_HANDLE * phPublicKey,
CK_OBJECT_HANDLE * phPrivateKey);

On successful return

*phPublicKey — handle to newly created public key

*phPrivateKey — handle to newly created private key

In addition to the Public key attributes set via the parameters, the following are set:

CKA_CLASS CKO_PUBLIC_KEY 
CKA_KEY_TYPE CKK_DSA 
CKA_VERIFY TRUE 
CKA_EXTRACTABLE TRUE

In addition to the Private key attributes set via the parameters, the following are set:

CKA_CLASS CKO_PRIVATE_KEY 
CKA_KEY_TYPE CKK_DSA 
CKA_SUBJECT_STR “SUBJECT” 
CKA_ID 123 
CKA_SENSITIVE TRUE 
CKA_SIGN TRUE 
CKA_EXTRACTABLE TRUE

The default values for the DSA parameters are:

512 P = fca682ce8e12caba26efccf7110e526db078b05edecbcd1eb4a208f3ae1617ae01f35b91a47e6df6 3413c5e12ed0899bcd132acd50d99151bdc43ee737592e17

512 Q = 962eddcc369cba8ebb260ee6b6a126d9346e38c5

512 G = 678471b27a9cf44ee91a49c5147db1a9aaf244f05a434d6486931d2d14271b9e35030b71fd73da 179069b32e2935630e1c2062354d0da20a6c416e50be794ca4

1024 P = e2662c8df32db56309ccb7f8f419e73263c55c1a89954fa68d85d8b09c720618532bd05dc0994b e245526367b08888f4ef07bb0977ac6aa3c4653f6d70151027fb73a9d7f99e63a63ea5c89de1b1 5b35ecc0beae18a89ee4aac0f75b2c364026c3b6ef8ad13cdd6886d93f9b86c71cb2537b449643 4412033ab3002de749d963

1024 Q = fd5274d166045c96e5f180ab181ccde55804a9c7

1024 G = 0c8392be4b9c222526fc2160864b117b7c8d9e3bec9faa1f7e4d8cfcecbfbf521a0aca11620aaaf0 f847068e8f6c936438bd482cd2d6ee2bbac519b63f5809c412dbd39664fa4e05567fc9bf01f83e3 f816aa945304f31e832a243e138b7b776bb519411d5669b4c6e38c840c2b9ae195f84f04b8b508 7271613c12d938720cc

GenerateRsaKeyPair

Generate an RSA key pair.

Synopsis

CK_RV GenerateRsaKeyPair(
CK_SESSION_HANDLE hSession,
char * txt,
int ftok,
int priv,
CK_SIZE modulusBits,
int expType,
CK_OBJECT_HANDLE * phPublicKey,
CK_OBJECT_HANDLE * phPrivateKey);

On successful return

*phPublicKey — handle to newly created public key

*phPrivateKey — handle to newly created private key

In addition to the Public key attributes set via the parameters, the following are set:

CKA_CLASS CKO_PUBLIC_KEY 
CKA_KEY_TYPE CKK_RSA 
CKA_SUBJECT_STR “SUBJECT” 
CKA_ENCRYPT TRUE 
CKA_VERIFY TRUE 
CKA_WRAP FALSE 
CKA_EXTRACTABLE TRUE

In addition to the Private key attributes set via the parameters, the following are set:

CKA_CLASS 
CKO_PRIVATE_KEY 
CKA_KEY_TYPE 
CKK_RSA 
CKA_SUBJECT_STR “SUBJECT” 
CKA_ID 123 
CKA_SENSITIVE TRUE 
CKA_DECRYPT TRUE 
CKA_SIGN TRUE 
CKA_UNWRAP FALSE 
CKA_EXTRACTABLE TRUE

GetAttr

Get a single attribute of an object.

Synopsis

CK_RV GetAttr(
CK_SESSION_HANDLE hSession,
CK_OBJECT_HANDLE obj,
CK_ATTRIBUTE_TYPE type,
CK_VOID_PTR buf,
CK_SIZE len,
CK_SIZE_PTR size);

On successful return

buf — contains the attribute value

*size — number of bytes copied to buf

If buf is too small to hold the attribute value (that is, len is < attribute value length), then CKR_ATTRIBUTE_TYPE_INVALID is returned.

To determine the attribute value length, pass in 0 for len, and check the resulting value of *size.

getDerEncodedNamedCurve

Access curve OIDs from the Cryptoki library. Previous JCPROV versions require explicitly coded elliptic curve OIDs in Java code. The JCPROV enhancement allows Java to get curve OIDs from the Cryptoki library.

Synopsis

getDerEncodedNamedCurve <pszCurveName>

To get curve OIDs from the Cryptoki library

To use JCPROV to get curve OIDs from the Cryptoki Library include the following syntax in the Java code:

{
    LongRef oidBufLen = new LongRef();

    CTUtilEx.CTU_DerEncodeNamedCurve(pszCurveName.getBytes(),
            null, oidBufLen);
    //System.out.println("oidBufLen=" + (int)oidBufLen.value);
    byte[] oidBuf = new byte[(int)oidBufLen.value];
    CTUtilEx.CTU_DerEncodeNamedCurve(pszCurveName.getBytes(),
            oidBuf, oidBufLen);
    //System.out.println("oidBufLen=" + (int)oidBufLen.value);
    return oidBuf;
}

...where the pszCurveName variable can be assigned to P-192, ..., brainpoolP512t1 values.

GetDeviceError

Returns the device-error value for a given slot ID

Synopsis

CK_RV GetDeviceError( CK_SLOT_ID slotID,CK_NUMERIC *pDeviceError);

On successful return

*pDeviceError — returned error code

GetObjectCount

Determine the number of objects on a token.

Synopsis

CK_RV GetObjectCount(
CK_SLOT_ID slotID,
unsigned int * pCount);

On successful return

*pCount — number of objects

GetSecurityMode

Get the security mode for the slot id given by inputSlotID.

Synopsis

CK_RV GetSecurityMode(CK_SLOT_ID inputSlotId,
CK_SLOT_ID* pAdminSlotId,
CK_FLAGS* pSecMode);

On successful return

*pStringVal — pointer to the returned string value

*pStringValLen — length of the string

GetSessionCount

Determine the number of sessions on a token

Synopsis

CK_RV GetSessionCount(
CK_SLOT_ID slotID,
unsigned int * pSessionCount,
unsigned int *prwSessionCount);

On successful return

*pSessionCount — number of open session

*prwSessionCount — number of open RW session

GetTotalSessionCount

Determine the total number of sessions open on all tokens on all adapters.

Synopsis

CK_RV GetTotalSessionCount(
unsigned int *pSessionCount);

On successful return

*pSessionCount — total number of open sessions

NUMITEMS

This is a macro that returns the number of elements in an array.

It is used wherever object templates are defined since the number of items in the template is always passed along with the template address into Cryptoki functions. Use of this macro is preferred to hard coding the number of items in the template that may change with code maintenance.

Synopsis

#define NUMITEMS(type)  (sizeof((type))/sizeof((type)[0]))

rmTrailSpace

Remove trailing spaces from a string.

Synopsis

void rmTrailSpace(
char * txt,
int len);

On successful return

txt — string no longer has trailing spaces

SetAttr

Set a single attribute of an object.

Synopsis

CK_RV SetAttr(
CK_SESSION_HANDLE hSession,
CK_OBJECT_HANDLE obj,
CK_ATTRIBUTE_TYPE type,
const CK_VOID_PTR buf,
CK_SIZE len);

ShowSlot

Dump slot details via printf.

Synopsis

CK_RV ShowSlot(
CK_SLOT_ID slotID,
int verbose);

ShowToken

Dump token details via printf.

Synopsis

CK_RV ShowToken(
CK_SLOT_ID slotID,
int verbose);

strAttribute

Given the numeric value of an attribute, return the string name.

Synopsis

char * strAttribute(
CK_NUMERIC val);

strError

Given the numeric value of an error, return the string name.

Synopsis

char * strError(
CK_NUMERIC val);

strKeyType

Given the numeric value of a key type, return the string name.

Synopsis

char * strKeyType(
CK_NUMERIC val);

strMechanism

Given the numeric value of a mechanism, return the string name.

Synopsis

char * strMechanism(
CK_NUMERIC val);

strObjClass

Given the numeric value of an object class, return the string name.

Synopsis

char * strObjClass(
CK_NUMERIC val);

strSesState

Given the numeric value of a session state, return the string name.

Synopsis

char * strSesState(
CK_NUMERIC val);

TransferObject

Copies an object from one Token to another.

Synopsis

CK_RV TransferObject(
CK_SESSION_HANDLE sTo,
CK_SESSION_HANDLE sFrom,
CK_OBJECT_HANDLE hObj,
CK_OBJECT_HANDLE * phObj,
CK_ATTRIBUTE_PTR pTemplate,
CK_COUNT ulCount);

On successful return

*phObj — handle to newly copied object

pTemplate — can only overwrite attributes which are ordinarily writeable.

This function tries the following methods to copy the object, in order:

1. Using the CKM_ENCODE_ATTRIBUTES vendor defined key wrapping mechanism to transfer keys.

2. Reading all the attributes of the existing object and creating a new object with them.

valAttribute

Given the string name of an attribute, return the numeric value.

Synopsis

CK_NUMERIC valAttribute(
const char * txt);

valError

Given the string name of an error, return the numeric value.

Synopsis

CK_NUMERIC valError(
const char * txt);

valKeyType

Given the string name of a key type, return the numeric value.

Synopsis

CK_NUMERIC valKeyType(
const char * txt);

valMechanism

Given the string name of a mechanism, return the numeric value.

Synopsis

CK_NUMERIC valMechanism(
const char * txt);

valObjClass

Given the string name of an object class, return the numeric value.

Synopsis

CK_NUMERIC valObjClass(
const char * txt);

valSesState

Given the string name of a session state, return the numeric value.

Synopsis

CK_NUMERIC valSesState(
const char * txt);